// --------------------------------------------------------------------------------------------
// Version: MPL 1.1/GPL 2.0/LGPL 2.1
// 
// The contents of this file are subject to the Mozilla Public License Version
// 1.1 (the "License"); you may not use this file except in compliance with
// the License. You may obtain a copy of the License at
// http://www.mozilla.org/MPL/
// 
// Software distributed under the License is distributed on an "AS IS" basis,
// WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
// for the specific language governing rights and limitations under the
// License.
// 
// <remarks>
// Generated by IDLImporter from file mozIStorageService.idl
// 
// You should use these interfaces when you access the COM objects defined in the mentioned
// IDL/IDH file.
// </remarks>
// --------------------------------------------------------------------------------------------
namespace Gecko
{
	using System;
	using System.Runtime.InteropServices;
	using System.Runtime.InteropServices.ComTypes;
	using System.Runtime.CompilerServices;
	
	
	/// <summary>
    /// The mozIStorageService interface is intended to be implemented by
    /// a service that can create storage connections (mozIStorageConnection)
    /// to either a well-known profile database or to a specific database file.
    ///
    /// This is the only way to open a database connection.
    ///
    /// @note The first reference to mozIStorageService must be made on the main
    /// thread.
    /// </summary>
	[ComImport()]
	[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
	[Guid("07b6b2f5-6d97-47b4-9584-e65bc467fe9e")]
	public interface mozIStorageService
	{
		
		/// <summary>
        /// Open an asynchronous connection to a database.
        ///
        /// This method MUST be called from the main thread. The connection object
        /// returned by this function is not threadsafe. You MUST use it only from
        /// the main thread.
        ///
        /// If you have more than one connection to a file, you MUST use the EXACT
        /// SAME NAME for the file each time, including case. The sqlite code uses
        /// a simple string compare to see if there is already a connection. Opening
        /// a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
        ///
        /// @param aDatabaseStore Either a nsIFile representing the file that contains
        /// the database or a special string to open a special database. The special
        /// string may be:
        /// - "memory" to open an in-memory database.
        ///
        /// @param aOptions A set of options (may be null). Options may contain:
        /// - bool shared (defaults to |false|).
        /// -- If |true|, opens the database with a shared-cache. The
        /// shared-cache mode is more memory-efficient when many
        /// connections to the same database are expected, though, the
        /// connections will contend the cache resource. In any cases
        /// where performance matter, working without a shared-cache will
        /// improve concurrency.  @see openUnsharedDatabase
        ///
        /// - int growthIncrement (defaults to none).
        /// -- Set the growth increment for the main database.  This hints SQLite to
        /// grow the database file by a given chunk size and may reduce
        /// filesystem fragmentation on large databases.
        /// @see mozIStorageConnection::setGrowthIncrement
        ///
        /// @param aCallback A callback that will receive the result of the operation.
        /// In case of error, it may receive as status:
        /// - NS_ERROR_OUT_OF_MEMORY if allocating a new storage object fails.
        /// - NS_ERROR_FILE_CORRUPTED if the database file is corrupted.
        /// In case of success, it receives as argument the new database
        /// connection, as an instance of |mozIStorageAsyncConnection|.
        ///
        /// @throws NS_ERROR_INVALID_ARG if |aDatabaseStore| is neither a file nor
        /// one of the special strings understood by this method, or if one of
        /// the options passed through |aOptions| does not have the right type.
        /// @throws NS_ERROR_NOT_SAME_THREAD if called from a thread other than the
        /// main thread.
        /// </summary>
		[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType=MethodCodeType.Runtime)]
		void OpenAsyncDatabase([MarshalAs(UnmanagedType.Interface)] nsIVariant aDatabaseStore, [MarshalAs(UnmanagedType.Interface)] nsIPropertyBag2 aOptions, mozIStorageCompletionCallback aCallback);
		
		/// <summary>
        /// Get a connection to a named special database storage.
        ///
        /// @param aStorageKey a string key identifying the type of storage
        /// requested.  Valid values include: "memory".
        ///
        /// @see openDatabase for restrictions on how database connections may be
        /// used. For the profile database, you should only access it from the main
        /// thread since other callers may also have connections.
        ///
        /// @returns a new mozIStorageConnection for the requested
        /// storage database.
        ///
        /// @throws NS_ERROR_INVALID_ARG if aStorageKey is invalid.
        /// </summary>
		[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType=MethodCodeType.Runtime)]
		mozIStorageConnection OpenSpecialDatabase([MarshalAs(UnmanagedType.LPStr)] string aStorageKey);
		
		/// <summary>
        /// Open a connection to the specified file.
        ///
        /// Consumers should check mozIStorageConnection::connectionReady to ensure
        /// that they can use the database.  If this value is false, it is strongly
        /// recommended that the database be backed up with
        /// mozIStorageConnection::backupDB so user data is not lost.
        ///
        /// ==========
        /// DANGER
        /// ==========
        ///
        /// If you have more than one connection to a file, you MUST use the EXACT
        /// SAME NAME for the file each time, including case. The sqlite code uses
        /// a simple string compare to see if there is already a connection. Opening
        /// a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
        ///
        /// The connection object returned by this function is not threadsafe. You must
        /// use it only from the thread you created it from.
        ///
        /// @param aDatabaseFile
        /// A nsIFile that represents the database that is to be opened..
        ///
        /// @returns a mozIStorageConnection for the requested database file.
        ///
        /// @throws NS_ERROR_OUT_OF_MEMORY
        /// If allocating a new storage object fails.
        /// @throws NS_ERROR_FILE_CORRUPTED
        /// If the database file is corrupted.
        /// </summary>
		[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType=MethodCodeType.Runtime)]
		mozIStorageConnection OpenDatabase([MarshalAs(UnmanagedType.Interface)] nsIFile aDatabaseFile);
		
		/// <summary>
        /// Open a connection to the specified file that doesn't share a sqlite cache.
        ///
        /// Without a shared-cache, each connection uses its own pages cache, which
        /// may be memory inefficient with a large number of connections, in such a
        /// case so you should use openDatabase instead.  On the other side, if cache
        /// contention may be an issue, for instance when concurrency is important to
        /// ensure responsiveness, using unshared connections may be a performance win.
        ///
        /// ==========
        /// DANGER
        /// ==========
        ///
        /// If you have more than one connection to a file, you MUST use the EXACT
        /// SAME NAME for the file each time, including case. The sqlite code uses
        /// a simple string compare to see if there is already a connection. Opening
        /// a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
        ///
        /// The connection object returned by this function is not threadsafe. You must
        /// use it only from the thread you created it from.
        ///
        /// @param aDatabaseFile
        /// A nsIFile that represents the database that is to be opened.
        ///
        /// @returns a mozIStorageConnection for the requested database file.
        ///
        /// @throws NS_ERROR_OUT_OF_MEMORY
        /// If allocating a new storage object fails.
        /// @throws NS_ERROR_FILE_CORRUPTED
        /// If the database file is corrupted.
        /// </summary>
		[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType=MethodCodeType.Runtime)]
		mozIStorageConnection OpenUnsharedDatabase([MarshalAs(UnmanagedType.Interface)] nsIFile aDatabaseFile);
		
		/// <summary>
        /// See openDatabase(). Exactly the same only initialized with a file URL.
        /// Custom parameters can be passed to SQLite and VFS implementations through
        /// the query part of the URL.
        ///
        /// @param aURL
        /// A nsIFileURL that represents the database that is to be opened.
        /// </summary>
		[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType=MethodCodeType.Runtime)]
		mozIStorageConnection OpenDatabaseWithFileURL([MarshalAs(UnmanagedType.Interface)] nsIFileURL aFileURL);
		
		/// <summary>
        /// Copies the specified database file to the specified parent directory with
        /// the specified file name.  If the parent directory is not specified, it
        /// places the backup in the same directory as the current file.  This function
        /// ensures that the file being created is unique.
        ///
        /// @param aDBFile
        /// The database file that will be backed up.
        /// @param aBackupFileName
        /// The name of the new backup file to create.
        /// @param [optional] aBackupParentDirectory
        /// The directory you'd like the backup file to be placed.
        /// @return The nsIFile representing the backup file.
        /// </summary>
		[return: MarshalAs(UnmanagedType.Interface)]
		[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType=MethodCodeType.Runtime)]
		nsIFile BackupDatabaseFile([MarshalAs(UnmanagedType.Interface)] nsIFile aDBFile, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalType = "Gecko.CustomMarshalers.AStringMarshaler")] nsAStringBase aBackupFileName, [MarshalAs(UnmanagedType.Interface)] nsIFile aBackupParentDirectory);
	}
}
